Skip to main content

Availability

In order to access the MetaSearch Engine APIs, you should target a site through its URL along with:

  • http://[site-url]/api/jobboard/v1/{endpoint}, and
  • http://[site-url]/api/v1/system/{endpoint} for using webhooks and event payloads

In the previous example, endpoint corresponds to the action you are calling.

API specifications

Response and Request Formats​

  • These APIs work only with JSON as their transport format.
  • All JSON properties are named in camel case starting by lower case (e.g. customFields).
  • Dates follow the ISO 8601 standard.

Implementation Recommendations

  • The number of API calls must be kept to a minimum. The use of webhooks can help minimize the calls.
  • Errors must be corrected.
  • Request only one token for a given user session. Avoid requesting a new token between each API call and only request a new token when the current one has expired (the duration is mentioned in the authorization response, in the field expires_in - see below in the Authorization section).

Authorization

In order to interact with the APIs, the application will need to be identified through a client_id and a client_secret, using the url http://[site-url]/api/token. You will get a token that must be in the Authorization header of each API call.

The protocol involved is OAuth2.

How to retrieve a token​

  • “As an application”:
    • POST https://[site-url]/api/token HTTP/1.1
    • Content-Type: application/x-www-form-urlencoded
    • In the body:
        - client_id=[clientID]
        - client_secret=[clientSecret]
        - grant_type=client_credentials
        - scope=MetaEngine

The client_id and client_secret are unique per partner and per environment and can be configured by a Cegid technical consultant.

The response will contain the access token:

{
     "access_token": "433fKaLfINnJB46DhWIVFyoVmPzX3h7ZUauAfOaT046KyXqd0qFIkAa3MOAHHYgHKU9tF",
     "token_type": "bearer",
     "expires_in": 1199
}

The token obtained must be used in the Authorization header of every API call:

Authorization: bearer token, where token is the token retrieved.

How to use the access token​

  • GET /api/jobboard/v1/vacancies
    • In headers:
    Authorization = bearer 433fKaLfINnJB46DhWIVFyoVmPzX3h7ZUauAfOaT046KyXqd0qFIkAa3MOAHHYgHKU9tF

Cinematics

Cinematic of API calls to get all referentials needed for creating applications forms:​

  1. Retrieve a token “as an application” (grant_type=client_credentials): POST /api/token
  2. Get all referentials, by category (example for diplomas referential): GET /api/jobboard/v1/referentials/diplomas
  3. Get referentials translations using the id of a specific item. Two cases:
    • Get all available translations of referential item: GET /api/jobboard/v1/referentials/diplomas/{id}/translations
    • Get the item's translation in one specific language: GET /api/jobboard/v1/referentials/diplomas/{id}/translations/{lcid}

Cinematic of API calls to retrieve all vacancies available and display one:​

  1. Retrieve a token “as an application” (grant_type=credentials): POST /api/token
  2. Get a list of all vacancies: GET /api/jobboard/v1/vacancies
  3. Get the details of a specific vacancy: GET /api/jobboard/v1/vacancies/{vacancyReference}

We propose that you use the above cinematics only in the initialization process in order to retrieve all the vacancies posted in the front office. After having retrieved the initial information you can keep the vacancies lists up-to-date by using webhooks (see next section).

Cinematic of API calls to create an application on a vacancy:​

  1. Retrieve a token “as an application” (grant_type=credentials): POST /api/token
  2. Get a list of all vacancies: GET /api/jobboard/v1/vacancies
  3. Get the details of a specific vacancy: GET /api/jobboard/v1/vacancies/{vacancyReference}
  4. Apply to selected vacancy (documents can be attached): POST /api/jobboard/v1/vacancies/{vacancyReference}/applications (see example in the end of this document)

Cinematic of API calls to follow up on a candidates applications status:​

  1. Retrieve a token “as an application” (grant_type=credentials): POST /api/token
  2. Retrieve a list of the candidate's applications: GET /api/jobboard/v1/candidates/{id}/applications

Note: For the list of available endpoints, more technical details on the MetaEngine APIs as well as the full list of available referentials please visit the Cegid documentation page on this topic.

Example of the body of a request for the creation of an application​

To call the endpoint POST /api/jobboard/v1/vacancies/{vacancyReference}/applications the request body should be of the following structure:

    {"candidateInformation":{
          "lastName":"candidate_lastName",
          "firstName":"candidate_firstName",
          "phoneNumber":"0123456789",
          "email":"test@test.com",
          "personalEmail":"test@test.com"
        },
       "gdprInformation":{
          "personalDataConsentReceived":true,
          "retentionDelay":12
       }
    }

Note: The above is a minimal working example therefore it does not contain all available fields for a vacancy application. Depending on the client configuration, other fields, not mentioned, might be mandatory. For real applications, we encourage using additionally at least the fields educations, jobPreferences as well as location information fields included in the block personalInformation.

Use of Webhooks

The use of webhooks is available for the MetaEngine use case which allows you to get notified when there are changes such as new vacancies/applicants or modifications on existing vacancies/applicants. You can subscribe to an event in order to receive notifications when the event is triggered.

By default, the mechanism to call peers to inform them of any change is triggered every 15 minutes but can be modified by the client.

To register to an event you must first retrieve a token “as an application” (grant_type=client_credentials): POST /api/token.

To subscribe to the event you must call the endpoint: POST /api/system/v1/webhooks

In the body of the request you must specify the event you want to subscribe to, a callback URL on which Recruiting may call the subscriber and a ping URL on which Recruiting may call when a ping is requested. For example if you want to get notified when new vacancies are available:

POST /api/system/v1/webhooks
Authorization: Bearer /* Oauth2 token */

{
 "event": "vacancy_new",
 "callbackUrl": "https://example.com/api/talentsoft/v1/events",
 "pingUrl": "https://example.com/api/talentsoft/v1/pingevents" 
}

The response will contain a hookId which can be used to unsubscribe from the event using the endpoint: DELETE /api/system/v1/webhooks/{hookId}

Note: Some events which may be useful for this use case are vacancy_new, vacancy_update. For the complete list of webhook events available for subscription please visit this page.